---
description: "Reference for Nitric's v0 Python library - Create APIs with the Nitric Python SDK."
---

# Python - api()

Creates a new HTTP API.

```python
from nitric.resources import api

publicApi = api("public")
```

## Parameters

<Properties>
  <Property name="name" required type="string">
    The unique name of this API within the app. Subsequent calls to `api` with
    the same name will return the same object.
  </Property>
  <Property name="options" type="object" optional>
    Additional options when creating the API.
    <Properties nested>
      <Property name="path" type="string" optional>
        Base path for all routes in the API.
      </Property>
      <Property name="middleware" type="List[Middleware]" optional>
        Middleware to apply to all routes and methods of the API.
      </Property>
      <Property
        name="securityDefinitions"
        type="dict[str, SecurityDefinition]"
        optional
      >
        Security definitions defined by this API.
      </Property>
      <Property name="security" type="dict[str, List[str]]" optional>
        Security rules to apply with scopes to the entire API. Keys must match a
        `securityDefinition`.
      </Property>
    </Properties>
  </Property>
</Properties>

## SecurityDefinition Parameters

<Properties>
  <Property name="issuer" required type="string">
    The issuer for the JWT tokens e.g. `https://account.region.auth0.com`.
  </Property>
  <Property name="audiences" required type="string[]">
    The `aud` that will be applied to JWT tokens from the issuer.
  </Property>
</Properties>

---

### Notes

The `middleware` property on the `options` param is useful for applying universal middleware such as CORS headers, across an entire API from a single place.

## Examples

### Create an API

```python
from nitric.resources import api

publicApi = api("public")
```

### Create an API with universal middleware

```python
from nitric.resources import api, ApiOptions
from myapp.middleware import auth

publicApi = api("public", ApiOptions(middleware=[auth]))
```

### Define middleware

```python
async def auth(ctx, nxt: HttpMiddleware):
  # Perform auth validation.
  return await nxt(ctx)
```

### Notes

Middleware services are supplied a `HttpContext` object and a `next()` function which calls the next middleware in the chain.

### Create an API with a base path

If you need to put all the routes in your api below a shared base path, you can do that with the `path` option. In this example we ensure all routes start with `/api/v1/` before the route specific path.

```python
from nitric.resources import api, ApiOptions

publicApi = api("public", ApiOptions(path="/api/v1/"))
```

### Apply JWT authentication to an API

```python
from nitric.resources import api, ApiOptions
from nitric.resources.apis import JwtSecurityDefinition

publicApi = api("public", ApiOptions(
    security_definitions={
        "user": JwtSecurityDefinition(
            issuer="https://example-issuer.com",
            audiences=['YOUR-AUDIENCES']
        )
    },
    security={
        "user": []
    }
))
```
